#include"Queue.h"
/*
 * Desciption: Queue.c
 * 中文：一些重复的参数，函数代码说明。
 * @param q Pointer to the queue
 * @note Asserts the validity of the queue
 */

bool queueEmpty(Queue *q)
{
    assert(q);
    // When the queue is empty, the head pointer is NULL.队列为空时，头指针NULL.
    return q->phead == NULL;
}

/**
 * @brief Initialize Queue  初始化队列
 *
 * Initializes the given queue structure, setting both the head and tail pointers to NULL,
 * and setting the queue length to 0. 初始化给定的队列结构，设置队列的头尾指针为 NULL，并将队列长度设置为 0
 *
 */
void queueInit(Queue *q)
{
    assert(q);                 
    q->phead = q->ptail = NULL; // Initialize the head and tail pointers to NULL when the queue is empty 初始时队列为空，头尾指针都为NULL
    q->size = 0;                // Set the initial queue length to 0 初始队列长度设置为0.
}
void queueDestroy(Queue *q)
{
    assert(q);
    if (queueEmpty(q)) // If the queue is empty, return directly 队列为空,执行返回
    {
        fprintf(stderr, "The queue is not empty, so it cannot be destroyed\n");
        return;
    }
    // // When the queue is not empty, loop through and delete all elements in the queue 当队列不为空时，循环删除队列中所有元素.
    QNode *pcur = q->phead, *prev = NULL;
    while (pcur != NULL)
    {
        prev = pcur;
        pcur = pcur->next;
        free(prev); // Free the current node's memory 释放当前节点空间.
    }
    q->phead = q->ptail = NULL; // Set both head and tail pointers to NULL 头尾指针都为NULL.
}

/**
 * @brief Deletes the head element from the queue
 */
void deQueue(Queue *q)
{
    assert(q);
    if (queueEmpty(q)) // If the queue is empty, return directly 队列为空,执行返回
    {
        fprintf(stderr, "The queue is empty, so an element cannot be dequeued\n");
        return;
    }
    // Call the function to actually delete the head element 调用函数删除队头元素
    deleteQueueHead(q);
}

/**
 * @brief Deletes the head element from the queue
 */
void deleteQueueHead(Queue *q)
{
    // Point a temporary node to the head node 临时节点指向队头节点
    QNode *tmp = q->phead;

    // Update the head pointer to the next node 更新队头指针为下一个节点
    q->phead = tmp->next;

    // Free the memory occupied by the temporary node 释放临时节点所占用的内存
    free(tmp);

    // Decrement the queue size by 1.队列长度减1
    q->size--;
}

/**
 * @brief Enqueue an element at the tail of the queue. 入队操作---在队尾添加元素
 * @param x The value of the element to be added
 */
void enQueue(Queue *q, QDataType x)
{
    assert(q); // Ensure the queue pointer is not NULL

    // Allocate memory for a new node 分配新节点空间
    QNode *newnode = (QNode *)malloc(sizeof(QNode));
    if (newnode == NULL)
    {
        fprintf(stderr, "Memory allocation failed\n");
        return;
    }
    // Set the data value of the new node 设置新节点数据值
    newnode->data = x;
    newnode->next = NULL;
    if (queueEmpty(q))
    {
        // If the queue is empty, set the head and tail pointers to the new node
        q->phead = q->ptail = newnode;
    }
    else
    {
        // Add the new node to the end of the queue  将新节点添加到队尾
        q->ptail->next = newnode;
        // Update the queue's tail pointer to point to the new node 更新队尾指针为新节点
        q->ptail = newnode;
    }

    // Add one to the queue length 队列长度加1
    q->size++;
}

QDataType QueueBack(Queue *q)
{
    assert(q);
    return q->ptail->data;
}
QDataType QueueFront(Queue *q)
{
    assert(q);
    return q->phead->data;
}

/**
 * @brief Get the size of the queue 获取队列大小
 *
 * Returns the current size (number of elements) of the given queue.返回给定队列的当前大小（元素数量）
 * @return Size of the queue (number of elements)
 */
int QueueSize(Queue *q)
{
    assert(q);
    return q->size;
}
